---
title: 'File picker dialog'
sidebarTitle: 'File picker'
description: 'Open a file picker dialog in a Kotlin Multiplatform project'
---

<Check>Supported on Android, iOS, macOS, JVM, JS and WASM targets</Check>

## Quick start

The file picker component provides a native interface for users to browse and select files from their device. It supports various file types and offers customization options to fit different use cases.

<CodeGroup>
```kotlin filekit-dialogs
val file = FileKit.openFilePicker()
```

```kotlin filekit-dialogs-compose
val launcher = rememberFilePickerLauncher { file ->
    // Handle the file
}

Button(onClick = { launcher.launch() }) {
    Text("Pick a file")
}
```
</CodeGroup>

## Selection mode

Select one or multiple files using the `mode` parameter. FileKit provides four different selection modes:

### Basic modes
- `Single` - Allows the user to select a single file (default).
- `Multiple()` - Allows the user to select multiple files.

<CodeGroup>
```kotlin filekit-dialogs
// Single file selection
val file = FileKit.openFilePicker(mode = FileKitMode.Single)

// Multiple file selection
val files = FileKit.openFilePicker(mode = FileKitMode.Multiple())

// Multiple with max limit
val files = FileKit.openFilePicker(mode = FileKitMode.Multiple(maxItems = 5))
```

```kotlin filekit-dialogs-compose
// Single file selection
val singleLauncher = rememberFilePickerLauncher(
    mode = FileKitMode.Single
) { file ->
    // Handle single file: PlatformFile?
}

// Multiple file selection
val multipleLauncher = rememberFilePickerLauncher(
    mode = FileKitMode.Multiple(maxItems = 10)
) { files ->
    // Handle multiple files: List<PlatformFile>?
}
```
</CodeGroup>

### State-tracking modes

For advanced use cases where you need to track the selection progress:

- `SingleWithState` - Single file selection with state tracking.
- `MultipleWithState()` - Multiple file selection with state tracking.

<CodeGroup>
```kotlin filekit-dialogs
// Single file with state tracking
val stateFlow = FileKit.openFilePicker(mode = FileKitMode.MultipleWithState())
stateFlow.collect { state ->
    when (state) {
        is FileKitPickerState.Started -> println("Selection started with ${state.total} files")
        is FileKitPickerState.Progress -> println("Processing: ${state.processed.size} / ${state.total}")
        is FileKitPickerState.Completed -> println("Completed: ${state.result.size} files selected")
        is FileKitPickerState.Cancelled -> println("Selection cancelled")
    }
}
```

```kotlin filekit-dialogs-compose
// Single file with state tracking
val stateLauncher = rememberFilePickerLauncher(
    mode = FileKitMode.MultipleWithState()
) { state ->
    when (state) {
        is FileKitPickerState.Started -> {
            // Show loading indicator
            println("Selection started with ${state.total} files")
        }
        is FileKitPickerState.Progress -> {
            // Update progress for: state.processed
            println("Processing: ${state.processed.size} / ${state.total}")
        }
        is FileKitPickerState.Completed -> {
            // Handle selected file: state.result
            println("Completed: ${state.result.size} files selected")
        }
        is FileKitPickerState.Cancelled -> {
            // Handle cancellation
            println("Selection cancelled")
        }
    }
}
```
</CodeGroup>

<Info>
The `Multiple` and `MultipleWithState` modes support a `maxItems` parameter to limit the number of files a user can select (1-50 files). If not specified, there's no limit.
</Info>

## Filter by type

Filter the files by their type using the `type` parameter. You can pick different types of files with `FileKitType`:
- `Image`: Pick an image file.
- `Video`: Pick a video file.
- `ImageAndVideo`: Pick an image or a video file.
- `File()`: Pick any file. It is the default type. It's possible to specify a list of extensions.

<CodeGroup>
```kotlin filekit-dialogs
val file = FileKit.openFilePicker(type = FileKitType.File(listOf("pdf", "docx")))
```

```kotlin filekit-dialogs-compose
val launcher = rememberFilePickerLauncher(
    type = FileKitType.File(extensions = listOf("pdf", "docx"))
) { file ->
    // Handle the pdf or docx file
}
```
</CodeGroup>

<Info>On Android and iOS, using Image, Video or ImageAndVideo FileKitType will open a gallery picker. [Read more here.](/dialogs/gallery-picker)</Info>

## Customizing the dialog

You can customize the dialog by setting the title, the initial directory and some settings relative to the platform.

<CodeGroup>
```kotlin filekit-dialogs
val file = FileKit.openFilePicker(
    title = "Custom title",
    directory = PlatformFile("/custom/initial/path"),
    dialogSettings = FileKitDialogSettings.createDefault()
)
```

```kotlin filekit-dialogs-compose
val launcher = rememberFilePickerLauncher(
    title = "Custom title",
    directory = PlatformFile("/custom/initial/path"),
    dialogSettings = FileKitDialogSettings.createDefault()
) { file ->
    // Handle the file
}
```
</CodeGroup>

Read more about [dialog settings](/dialogs/dialog-settings) to customize the dialog for each platform.

<Note>
  **macOS System Appearance**

  On macOS, to ensure the file picker dialog uses the system's theme (light or dark), you may need to set a system property at the start of your application:

  ```kotlin
  System.setProperty("apple.awt.application.appearance", "system")
  ```

  This is typically done in your `main` function, before the application window is created.
</Note>